/*
 * Copyright (c) 2005, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */
/*
 * $Id: XMLCryptoContext.java,v 1.6 2005/05/10 15:47:42 mullan Exp $
 */
package javax.xml.crypto;

/**
 * Contains common context information for XML cryptographic operations.
 *
 * <p>This interface contains methods for setting and retrieving properties
 * that affect the processing of XML signatures or XML encrypted structures.
 *
 * <p>Note that <code>XMLCryptoContext</code> instances can contain information
 * and state specific to the XML cryptographic structure it is used with.
 * The results are unpredictable if an <code>XMLCryptoContext</code> is
 * used with multiple structures (for example, you should not use the same
 * {@link javax.xml.crypto.dsig.XMLValidateContext} instance to validate two
 * different {@link javax.xml.crypto.dsig.XMLSignature} objects).
 *
 * @author Sean Mullan
 * @author JSR 105 Expert Group
 * @since 1.6
 */
public interface XMLCryptoContext {

  /**
   * Returns the base URI.
   *
   * @return the base URI, or <code>null</code> if not specified
   * @see #setBaseURI(String)
   */
  String getBaseURI();

  /**
   * Sets the base URI.
   *
   * @param baseURI the base URI, or <code>null</code> to remove current value
   * @throws IllegalArgumentException if <code>baseURI</code> is not RFC 2396 compliant
   * @see #getBaseURI
   */
  void setBaseURI(String baseURI);

  /**
   * Returns the key selector for finding a key.
   *
   * @return the key selector, or <code>null</code> if not specified
   * @see #setKeySelector(KeySelector)
   */
  KeySelector getKeySelector();

  /**
   * Sets the key selector for finding a key.
   *
   * @param ks the key selector, or <code>null</code> to remove the current setting
   * @see #getKeySelector
   */
  void setKeySelector(KeySelector ks);

  /**
   * Returns a <code>URIDereferencer</code> that is used to dereference
   * {@link URIReference}s.
   *
   * @return the <code>URIDereferencer</code>, or <code>null</code> if not specified
   * @see #setURIDereferencer(URIDereferencer)
   */
  URIDereferencer getURIDereferencer();

  /**
   * Sets a <code>URIDereferencer</code> that is used to dereference
   * {@link URIReference}s. The specified <code>URIDereferencer</code>
   * is used in place of an implementation's default
   * <code>URIDereferencer</code>.
   *
   * @param dereferencer the <code>URIDereferencer</code>, or <code>null</code> to remove any
   * current setting
   * @see #getURIDereferencer
   */
  void setURIDereferencer(URIDereferencer dereferencer);

  /**
   * Returns the namespace prefix that the specified namespace URI is
   * associated with. Returns the specified default prefix if the specified
   * namespace URI has not been bound to a prefix. To bind a namespace URI
   * to a prefix, call the {@link #putNamespacePrefix putNamespacePrefix}
   * method.
   *
   * @param namespaceURI a namespace URI
   * @param defaultPrefix the prefix to be returned in the event that the the specified namespace
   * URI has not been bound to a prefix.
   * @return the prefix that is associated with the specified namespace URI, or
   * <code>defaultPrefix</code> if the URI is not registered. If the namespace URI is registered but
   * has no prefix, an empty string (<code>""</code>) is returned.
   * @throws NullPointerException if <code>namespaceURI</code> is <code>null</code>
   * @see #putNamespacePrefix(String, String)
   */
  String getNamespacePrefix(String namespaceURI, String defaultPrefix);

  /**
   * Maps the specified namespace URI to the specified prefix. If there is
   * already a prefix associated with the specified namespace URI, the old
   * prefix is replaced by the specified prefix.
   *
   * @param namespaceURI a namespace URI
   * @param prefix a namespace prefix (or <code>null</code> to remove any existing mapping).
   * Specifying the empty string (<code>""</code>) binds no prefix to the namespace URI.
   * @return the previous prefix associated with the specified namespace URI, or <code>null</code>
   * if there was none
   * @throws NullPointerException if <code>namespaceURI</code> is <code>null</code>
   * @see #getNamespacePrefix(String, String)
   */
  String putNamespacePrefix(String namespaceURI, String prefix);

  /**
   * Returns the default namespace prefix. The default namespace prefix
   * is the prefix for all namespace URIs not explicitly set by the
   * {@link #putNamespacePrefix putNamespacePrefix} method.
   *
   * @return the default namespace prefix, or <code>null</code> if none has been set.
   * @see #setDefaultNamespacePrefix(String)
   */
  String getDefaultNamespacePrefix();

  /**
   * Sets the default namespace prefix. This sets the namespace prefix for
   * all namespace URIs not explicitly set by the {@link #putNamespacePrefix
   * putNamespacePrefix} method.
   *
   * @param defaultPrefix the default namespace prefix, or <code>null</code> to remove the current
   * setting. Specify the empty string (<code>""</code>) to bind no prefix.
   * @see #getDefaultNamespacePrefix
   */
  void setDefaultNamespacePrefix(String defaultPrefix);

  /**
   * Sets the specified property.
   *
   * @param name the name of the property
   * @param value the value of the property to be set
   * @return the previous value of the specified property, or <code>null</code> if it did not have a
   * value
   * @throws NullPointerException if <code>name</code> is <code>null</code>
   * @see #getProperty(String)
   */
  Object setProperty(String name, Object value);

  /**
   * Returns the value of the specified property.
   *
   * @param name the name of the property
   * @return the current value of the specified property, or <code>null</code> if it does not have a
   * value
   * @throws NullPointerException if <code>name</code> is <code>null</code>
   * @see #setProperty(String, Object)
   */
  Object getProperty(String name);

  /**
   * Returns the value to which this context maps the specified key.
   *
   * <p>More formally, if this context contains a mapping from a key
   * <code>k</code> to a value <code>v</code> such that
   * <code>(key==null ? k==null : key.equals(k))</code>, then this method
   * returns <code>v</code>; otherwise it returns <code>null</code>. (There
   * can be at most one such mapping.)
   *
   * <p>This method is useful for retrieving arbitrary information that is
   * specific to the cryptographic operation that this context is used for.
   *
   * @param key the key whose associated value is to be returned
   * @return the value to which this context maps the specified key, or <code>null</code> if there
   * is no mapping for the key
   * @see #put(Object, Object)
   */
  Object get(Object key);

  /**
   * Associates the specified value with the specified key in this context.
   * If the context previously contained a mapping for this key, the old
   * value is replaced by the specified value.
   *
   * <p>This method is useful for storing arbitrary information that is
   * specific to the cryptographic operation that this context is used for.
   *
   * @param key key with which the specified value is to be associated with
   * @param value value to be associated with the specified key
   * @return the previous value associated with the key, or <code>null</code> if there was no
   * mapping for the key
   * @throws IllegalArgumentException if some aspect of this key or value prevents it from being
   * stored in this context
   * @see #get(Object)
   */
  Object put(Object key, Object value);
}
